Synchronizing Users with LDAP/Active Directory

Paged AD Synchronization

When user AD synchronization is enabled, synchronization is done by pages of 500 users (default value), instead of fetching whole query result content at once.

This is necessary because since Windows 2008, AD does not provide more than 5000 objects a time. It is also better not to deal with huge blocks of data.

• To use this feature on Windows, Windows LDAP API DLL has to be used and the c_accounts_global_ldap_usewindowsdll API variable has to be set to true.
• This feature is also available on Linux, but not on RHEL5 (or CentOS5). All other supported distributions use this algorithm.
• There is no possibility to switch it off directly or set the size of the page.

Synchronization of Entities

Entity which matches a filter is located under defined DN and its mail attribute is listed in an expected domain. IceWarp Server reads email aliases from these LDIF properties: mail, otherMailbox, proxyAddresses.

SMTP type values in these attributes, i.e. values that have SMTP:// prefix, are considered as additional aliases. In the case there is no type specified and there is no prefix with ":", the whole value is considered as an email during synchronization.

Example:

otherMailbox attribute: SMTP:john.doe@example.com

otherMailbox attribute: j.doe@example.com

otherMailbox attribute: X509: john@example.com

mail attribute: john@example.com 

Parsing LDIF containing such attribute values will result in john.doe and j.doe as additional aliases of the account with primary alias john.

You can exclude a user from synchronization by checking Exclude from Directory Service Synchronization checkbox on user's Options tab. If you check this box, the account will not be deleted by sync mechanism even if it ceases to match settings or is removed from directory server.

Impact of Filter on Synchronized Entities

Filter value determines which entities will be included in directory server reply. Thus, changing it will most probably lead to a loss of current accounts/groups and possibly to emerging of new ones. Also deleting the filter, unchecking the Synchronize users/groups checkbox in IceWarp Server older than 11.2.0 or setting Users/Group from AD will not exist locally in IceWarp Server 11.2.0 and the newer versions will certainly lead to a loss of all accounts/groups.

If you want to be safe from accidental account data loss while tuning the filter, use c_system_adsyncmaxdeletethreshold API variable set to 1. It prevents losing more than one account after filter update. If the change would cause removal of more than one account none is removed instead, if it would cause removal of exactly one account it will be done.

Identification of Entities

IceWarp Server recognizes entities via objectGUID or entryUUID by default. Administrators can even customize this behavior in the syncad.dat file. Just add the required alternative property name into the <guidsource>node. When no unique ID is found, IceWarp Server will consider the email address (attribute mail) as a unique identifier. In this mode, any change of the email address results in deleting current account in IceWarp Server and creating a new one with a new alias.

For more information refer to Personal Data Synchronization

Detection of Account Update

IceWarp Server uses the whenChanged or modifyTimestamp attribute to identify updates. The value returned in LDIF is compared to value stored in adsyncrec.dat during previous synchronization. If the value is different, a user update is detected and groupware data are read, parsed according to vCard mapping and stored.

Again, administrators can customize which property is used for this in the syncad.dat file ? the WHENCHANGEDSOURCE tag.

If there is no such a property, update cannot be recognized. Thus, vCard data is synchronized every time for every account. This can lead to a serious performance issue with groupware service. In such scenarios, we recommend to turn vCard data synchronization off. It is still possible to enable it for instance once a day. You can script it as CLI utility with the help of tool.exe or tool.sh.

Example:

Tool set system c_system_adsyncdisablevcardsync 1

Storage of Synchronization Metadata

The adsyncrec.dat file located under configuration directory is to store synchronization metadata. This file serves as a database of objectGUIDs, timestamps of last modifications, account types etc. IceWarp Server is able to delete orphaned records from this file. If you want to reset synchronization for a particular user, just delete its record from this file (the same applies for a whole domain).

The more accounts, the slower synchronization mechanism you can expect as this file grows up. IceWarp Server was tested with 22.000 accounts successfully.

Passwords Management

IceWarp Server does not know user password until user is successfully authenticated against LDAP server. We support only plain (not hashed) password formats for this action. Once authentication is made, IceWarp caches the password on its side, but any further authentication is still made against LDAP server. Cached copy is a must for IceWarp to be able to handle hashed passwords (sent via mechanisms like CRAM-MD5). Cached copy is stored on server permanently. Such behavior brings a few problems; password can be retrieved on IceWarp side and no service that uses hashed password is working for LDAP authenticated user unless password is known to IceWarp. So let's have a look on how to handle those problems.

To protect passwords from being read, set the c_accounts_policies_pass_denyexport API variable to true.

To overcome limitation for hashed password authentication methods is possible only by using plain one first. Note that VoIP service does not support plain authentication method up to current release (11.4.0). VoIP will not authenticate LDAP synced user unless password is known toIceWarp. OutlookSync plugin is capable to overcome this limitation if secure connection to incoming server (Settings/Login credentials tab) is configured - since version 11.3.1.5. We plan to implement support for hashed passwords used to authenticate on directory server in future.

Recommendations on the Library

We recommend using the windows.dll library on Windows system. It is not possible to do otherwise on 64-bit builds. But a 32-bit build (especially existing installations) can use the openldap.dll one. This library does not support paged results and sometimes is not performing well (broken charsets, 500 objects limit). Switch to the windows.dll library can be done by setting the c_accounts_global_ldap_usewindowsdll API variable to true (restart of control module afterward is required).

How AD Sync Determines User Full Name

Imagine that AD/LDAP sync mechanism uses the following variables:

• IW_FN
• IW_NAME
• IW_SURNAME
• IW_GIVEN_NAME

At first, sync mechanism generates vCard according to mapping defined in the {vcardmap} node of a domain. Sync settings are located in the configuration file syncad.dat. Then, the IW_FN variable is filled with the vCard FN value, which is, by default, {displayName} or {fn} retrieved by LDAP. When both are present, the latter one in LDIF wins. If neither of them is defined, FN is empty.

Default behavior comes from definition of FN:$ {displayName,fn} in default vCard map. Altering the definition in syncad.dat will change the behavior (displayName and fn are exact names of attributes in LDIF).

IW_NAME is a copy of the {name} attribute from LDIF. If it is not present, it remains undefined.

IW_SURNAME is the first semicolon separated item in the N attribute of the vCard generated by vCard mapping procedure. By default, this is the LDIF attribute of {sn}.

IW_GIVEN_NAME is the second semicolon separated item in the N attribute of the vCard generated by vCard mapping (the LDIF attribute of {givenName} is used by default).

Then IW_GIVEN_NAME is checked whether it contains comma. If so, sync check that N contains less than four semicolons. If both of the former is true, IW_GIVEN_NAME is stripped to be the string before comma (does apply for default vCard map).

Now, when we have these four variables set, let us see the real U_Name generation algorithm. It works in two steps.

First step:

• If DisplayNameFromADGivenName is set and IW_GIVEN_NAME and IW_SURNAME are not empty, U_Name := IW_GIVEN_NAME + ' '+ IW_SURNAME
• Otherwise, if IW_FN is not empty, U_Name := IW_FN

>

• Otherwise, if IW_NAME is defined, U_Name := IW_NAME

Second step:

• If U_Name was not filled or is empty string and at least one of IW_GIVEN_NAME and IW_SURNAME is not empty
• If IW_SURNAME is empty, U_Name := IW_GIVEN_NAME
• Else if IW_GIVEN_NAME is empty, U_Name := IW_SURNAME
• Else if both are not empty, U_Name := IW_GIVEN_NAME + ' '+ IW_SURNAME